Docusaurus i18n 國際化實戰完整教學：從零到多語言網站
本教學基於 COVIA 知識平台的實際 i18n 實作經驗，從繁體中文網站擴展至支援英文、日文、德文四種語言版本的完整歷程。
前言：為什麼需要 i18n？
當你的網站開始有國際訪客時（COVIA 有 50% 流量來自美國、加拿大、德國），提供多語言版本就變得至關重要。Docusaurus 提供了強大的 i18n 支援，但實作過程中有許多細節需要注意。
一、基礎設定：啟用 i18n
1.1 配置 docusaurus.config.js
在 docusaurus.config.js 中加入 i18n 設定：
module.exports = {
// ... 其他配置
i18n: {
defaultLocale: 'zh-TW', // 預設語言
locales: ['zh-TW', 'en', 'ja', 'de'], // 支援的語言列表
localeConfigs: {
'zh-TW': {
label: '繁體中文',
direction: 'ltr',
htmlLang: 'zh-TW',
},
en: {
label: 'English',
direction: 'ltr',
htmlLang: 'en-US',
},
ja: {
label: '日本語',
direction: 'ltr',
htmlLang: 'ja',
},
de: {
label: 'Deutsch',
direction: 'ltr',
htmlLang: 'de',
},
},
},
// ... 其他配置
};
1.2 在 Navbar 加入語言切換器
themeConfig: {
navbar: {
items: [
// 語言切換下拉選單
{
type: 'localeDropdown',
position: 'left', // 或 'right'
},
// ... 其他 navbar 項目
],
},
},
二、檔案結構：i18n 資料夾組織
執行以下指令自動產生 i18n 檔案結構：
npm run write-translations
這會產生以下結構：
i18n/
├── en/
│ ├── code.json # React 程式碼中的翻譯
│ ├── docusaurus-theme-classic/
│ │ ├── navbar.json # Navbar 項目翻譯
│ │ └── footer.json # Footer 翻譯
│ ├── docusaurus-plugin-content-docs/
│ │ └── current.json # 文檔側邊欄翻譯
│ └── docusaurus-plugin-content-pages/
│ └── index.js # 首頁翻譯
├── ja/
│ └── ... (同上結構)
└── de/
└── ... (同上結構)
三、內容翻譯：文檔與頁面
3.1 翻譯文檔
- 複製文檔結構：將
docs/資料夾複製到對應語言資料夾：
# 複製整個 docs 資料夾到英文版
cp -r docs/* i18n/en/docusaurus-plugin-content-docs/current/
# 複製到日文版
cp -r docs/* i18n/ja/docusaurus-plugin-content-docs/current/
# 複製到德文版
cp -r docs/* i18n/de/docusaurus-plugin-content-docs/current/
- 翻譯文檔內容：編輯每個語言版本的
.md檔案，翻譯內容但保持 frontmatter 結構。
3.2 翻譯首頁
- 複製首頁檔案：
cp src/pages/index.js i18n/en/docusaurus-plugin-content-pages/index.js
cp src/pages/index.js i18n/ja/docusaurus-plugin-content-pages/index.js
cp src/pages/index.js i18n/de/docusaurus-plugin-content-pages/index.js
- 翻譯首頁內容：編輯各語言版本的
index.js，翻譯所有文字內容。
3.3 翻譯 UI 元素
編輯各語言的 JSON 檔案：
navbar.json 範例：
{
"title": {
"message": "COVIA Knowledge Sharing Platform",
"description": "The title in the navbar"
},
"item.label.知識庫": {
"message": "Knowledge Base",
"description": "Navbar item with label 知識庫"
}
}
footer.json 範例：
{
"copyright": {
"message": "Copyright © 2025 COVIA — From Errors to Wisdom.",
"description": "The footer copyright"
}
}
四、常見問題與解決方案
4.1 問題：語言切換器在 docs 頁面失效
症狀：
- 在首頁切換語言正常
- 在 docs 頁面切換語言導致 404 錯誤
- 路徑出現
/ja/docs/intro找不到的情況
原因：
不同語言版本的 intro.md 檔案 slug 設定不一致。
解決方案：
統一所有語言版本的路徑結構，移除不一致的 slug: / 設定：
---
sidebar_position: 1
title: 文檔標題
# slug: / ← 移除這行，讓 Docusaurus 自動處理路徑
---
4.2 問題：Build 時出現 Broken Links 錯誤
症狀：
Error: Docusaurus found broken links!
Broken link on source page path = /:
-> linking to /docs/intro
解決方案： 更新所有首頁中的連結，確保指向正確的語言版本路徑：
// 原本的連結
href="/docs/"
// 修改為
href={useBaseUrl('/docs/intro')}
// 或針對不同語言版本
href="/en/docs/intro" // 英文版
href="/ja/docs/intro" // 日文版
4.3 問題：HTML 類型的 Navbar 項目無法自動翻譯
症狀：
使用 type: 'html' 的 navbar 項目不會自動切換語言。
解決方案：
- 考慮改用標準 navbar 項目類型
- 或在 HTML 中加入語言判斷邏輯：
{
type: 'html',
value: `<a class="navbar__link" href="/#section" onclick="
const path = window.location.pathname;
const isHomePage = path === '/' || path === '/en/' || path === '/ja/' || path === '/de/';
if (!isHomePage) {
let homeUrl = '/';
if (path.startsWith('/en/')) homeUrl = '/en/';
else if (path.startsWith('/ja/')) homeUrl = '/ja/';
else if (path.startsWith('/de/')) homeUrl = '/de/';
window.location.href = homeUrl + '#section';
} else {
document.querySelector('section.target')?.scrollIntoView({behavior: 'smooth'});
}
">連結文字</a>`,
}
五、建置與部署
5.1 本地測試
# 測試預設語言（繁體中文）
npm run start
# 測試英文版
npm run start -- --locale en
# 測試日文版
npm run start -- --locale ja
# 測試德文版
npm run start -- --locale de
5.2 建置所有語言版本
# 建置所有語言版本
npm run build
# 本地預覽建置結果
npm run serve
5.3 部署到 Cloudflare Pages
Cloudflare Pages 會自動處理多語言路由，只需：
- 推送程式碼到 GitHub
- Cloudflare Pages 自動建置
- 所有語言版本會自動部署到對應路徑
六、最佳實踐建議
6.1 維護一致性
- 路徑結構一致：所有語言版本保持相同的檔案結構
- Slug 設定一致：避免不同語言版本有不同的 slug 設定
- 連結格式一致：統一使用相對路徑或絕對路徑
6.2 翻譯工作流程
- 先完成預設語言：確保繁體中文版完整無誤
- 批次翻譯：一次翻譯一個完整功能或章節
- 定期同步：當預設語言更新時，及時同步其他語言版本
6.3 效能優化
- 按需載入：Docusaurus 會自動按語言分割程式碼
- CDN 快取：利用 Cloudflare 的全球 CDN 加速不同地區的訪問
- 字體優化：針對不同語言使用適合的字體子集
七、進階技巧
7.1 自動化翻譯更新檢查
建立腳本檢查哪些檔案需要更新翻譯：
# 比較不同語言版本的檔案修改時間
find docs -name "*.md" -newer i18n/en/docusaurus-plugin-content-docs/current
7.2 使用翻譯記憶庫
對於大量重複內容，可以：
- 建立術語對照表
- 使用翻譯工具的記憶功能
- 保持專有名詞的一致性
7.3 SEO 優化
為每個語言版本優化 SEO：
// 在各語言的 intro.md 中
---
title: COVIA Knowledge Platform // 各語言的標題
description: From AI to Web Development // 各語言的描述
keywords: [docusaurus, i18n, tutorial] // 各語言的關鍵字
---
八、疑難排解檢查清單
遇到 i18n 問題時，依序檢查：
-
docusaurus.config.js的 i18n 設定是否正確？ - 所有語言資料夾結構是否一致？
- 各語言版本的 slug 設定是否相同？
- 首頁連結是否指向正確的語言路徑？
- JSON 翻譯檔案格式是否正確？
- Build 時是否有 broken links 警告？
- 語言切換器在所有頁面都能正常運作？
總結
Docusaurus 的 i18n 功能強大且靈活，但需要注意許多細節。透過 COVIA 的實戰經驗，我們學到：
- 簡單原則：保持路徑和結構的簡單一致
- 漸進實作：先做好單一語言，再逐步擴展
- 持續測試：每次修改都要測試所有語言版本
- 文檔記錄：記錄所有遇到的問題和解決方案
希望這份基於實戰的教學能幫助你順利建立多語言 Docusaurus 網站！
相關資源：